"FMTDOC" -- Documentation for FMTLEX, HP-71 String Format lexfile

        Lexfile by Hewlett-Packard
        Documentation by Joseph K. Horn

FMTLEX is an HP-71 language extension file.  When present in memory, a new BASIC
keyword is available (IMAGE$), and two native keywords become enhanced (PRINT
and USING).  This documentation describes how to use these features.

+--------+
! IMAGE$ !
+--------+

Although USING is a powerful feature of HP-71 BASIC, its execution is very slow.
The HP-71 design team had no choice.  Since USING can take a string variable as
its image (as in PRINT USING I$), there is no way to pre-tokenize the image.
This means that the image must be "figured out" during the run, instead of when
the program line is typed.  This slows down program execution.

FMTLEX adds the IMAGE$ function to overcome this problem.  If you plan on using
an unchanging image in a program, you can use IMAGE$ to "pre-tokenize" it into
a variable, for example I$=IMAGE$("3dc3d.2d").  Then, when this pre-tokenized
image is used (e.g. PRINT USING I$), FMTLEX recognizes it as pre-tokenized, and
skips the usual tokenization, thus speeding up program execution considerably.

Note: IMAGE$(A$) is always longer than A$, so if you wish to store it in a
variable you must dimension it to be big enough.  Here's a simple way to do it:

     DIM I$[LEN(IMAGE$(A$))]
     I$=IMAGE$(A$)

Here's a simple example of IMAGE$ in use in a program:

     100 A$="3dc3d.2d"
     110 DIM I$[LEN(IMAGE$(A$))] @ I$=IMAGE$(A$)
     120 FOR X=1 TO 20
     130 PRINT USING I$;RND*1E6
     140 NEXT X

This prints 20 random numbers between 0 and 999,999.99 in tabular form with
embeded comma and decimal point.  Notice how fast it runs.  To compare it with
"normal" speed, delete line 110 and change the I$ in line 130 to A$.  Using
IMAGE$ produces approximately a 30% increase in speed.

+---------------------+
! PRINT TO (variable) !
+---------------------+

FMTLEX upgrades the native PRINT command, allowing its output to be directed to
a string variable.  This is done by using the syntax PRINT TO (variable).
The rule is: set up the PRINT statement exactly like normal, but put TO A$ (or
any string variable) immediately after the PRINT.  The output will be identical
to normal, but will be directed into the variable.

For example, PRINT 153;18;"HELLO" normally prints " 153  18 HELLO" on the
printer (or display).  PRINT TO A$ ;153;18;"HELLO" puts the same output into
A$, with trailing carriage-return and line-feed.

Just remember to put a semicolon (;) after the target string variable, to
separate it from the list of things to be printed.  You may use semicolons or
commas between items in the list in the same way as in normal PRINTing.

You may combine PRINT TO with PRINT USING:

PRINT TO A$ USING I$;1,2,3

prints 1,2,3 into A$ using the I$ image, which may be pre-tokenized by using
IMAGE$ as described above.

Of course, you may also use a literal image string or a line number to specify
the IMAGE, as in PRINT TO A$ USING 100 or PRINT TO A$ USING "#,k/".

Since PRINT normally sends the ENDLINE sequence at the end of its output,
PRINT TO does also.  Defeating this is done for PRINT TO the same way as it is
for PRINT.  If you are using a plain PRINT TO, follow the last item with a
semicolon (;).  If you are using PRINT TO A$ USING I$, then the only way to
suppress the ENDLINE sequence from being sent is by having "#," at the
beginning of the image string (see HP-71 Reference Manual, page 138).

For example, PRINT TO A$ ;153; suppresses the trailing carriage-return and
line-feed.  Also, PRINT TO A$ USING "#,6z";153 does too.

BUG NOTICE: Although a line number may be used as the image specifier, this
should be avoided, because FMTLEX does not handle the RENUMBER poll.  This
means that RENUMBER does not renumber the line numbers in a PRINT TO USING
instruction.  Even worse, it does not handle the decompile poll (pZERPG), which
zeros out invalid offsets.  This means that modifications to the program after
it has been RUN do not decompile, which can result in erroneous offsets embedded
in the code.  The result of this is the "Invalid IMAGE" error, even though the
actual IMAGE line is perfectly valid.  There are two remedies: (1) FETCH the
lines containing the PRINT TO USING commands, and press ENDLINE, thereby forcing
them to decompile (one at a time); or (2) don't use line numbers with PRINT TO
USING, but use literal or variable strings instead.

In short:

              PRINT TO A$ USING 100;X;Y;Z;         is BAD! (line number 100)

              PRINT TO A$ USING B$;X;Y;Z;          is OK! (variable image)
              PRINT TO A$ USING "2d.4d";X;Y;Z;     is OK! (literal image)

jkh 11 Aug 89